feat(attachments): image and PDF attachments for widget and worker - #150

Description

Lets visitors attach images (JPEG/PNG/GIF/WebP) and PDFs to a message and have Claude analyze them via native image / document content blocks.

Widget

• New attachments option (React prop, window.ClaudiusConfig key, and <claudius-chat attachments> attribute). Off by default; true enables the defaults (5 MB per file, 5 files per message), or pass { maxSizeBytes, maxCount, allowedTypes }.
• Click-to-upload (paperclip), drag-and-drop onto the composer, and paste from the clipboard, with client-side validation and localized error messages in en/es/fr/de.
• Image thumbnails and PDF filename chips for pending files and inside message bubbles.
• ChatApiClient switches to multipart/form-data whenever a message carries inline bytes. Persisted history never contains bytes. When the worker stores an upload (R2 mode) the widget keeps the storage key + signed URL instead of the data. A worker-rejected upload rolls the message back and shows a translated error.

Worker

• attachments.ts: JSON and multipart request parsing, MIME allowlist plus magic-byte verification, per-file / per-message / per-request caps, and Anthropic content-block construction (files first, text last).
• attachment-storage.ts: passthrough (default, nothing stored) or r2 (stored under att/<tenant>/<uuid> for ATTACHMENT_RETENTION_HOURS, with HMAC-signed download URLs served by GET /api/attachments/*, lazy deletion after expiry).
• attachment-quota.ts: per-IP and per-tenant daily upload-byte quotas in the existing RATE_LIMIT KV.
• New error codes: ATTACHMENTS_DISABLED (400), ATTACHMENT_INVALID (400), ATTACHMENT_TOO_LARGE (413), ATTACHMENT_QUOTA_EXCEEDED (413 + Retry-After).

Config & docs

• clients/_schema.json, CLI validation, and snippet generation support widget.attachments and worker.attachments.
• New docs page configuration/attachments.md covering limits, storage backends, and the privacy posture (where files live, how long, who can read them), plus updates to the REST reference, widget/worker/clients config pages, FAQ, wrangler.toml, and .dev.vars.example.

Design notes for reviewers:

• The wire format stays backward compatible: plain conversations still post JSON with string content.
• Quotas count only the newest message's inline uploads so passthrough re-sends of history don't burn the budget; the per-request byte budget (ATTACHMENT_MAX_REQUEST_BYTES) drops history bytes oldest-first.
• Cloudflare R2 has no native presigned URLs without S3 keys, so signed links are worker-verified HMACs over key:exp.

Related Issue

Closes #53

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Documentation update
• Chore (dependency updates, CI changes, refactoring)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• Tests pass (pnpm test in both widget/ and worker/) — widget 323, worker 97, scripts 56
• Linting passes (pnpm lint in widget/)
• Formatting passes (pnpm format:check in widget/)
• Types check (pnpm typecheck in widget/)
• Widget builds successfully (cd widget && pnpm build)
• Documentation updated (if applicable)
• Branch name follows convention (feat/, fix/, docs/, chore/) — uses the repo's existing <issue>-<slug> pattern

Screenshots / Notes

• Not verified end to end against a live Anthropic key or a real R2 bucket; the worker paths are covered by route-level tests with mocked SDK/KV/R2. The docs site was not built locally (no docs/node_modules).
• Storybook: ChatInput › WithAttachments / WithPendingAttachments and ChatMessage › WithAttachments.

🤖 Generated with Claude Code